
package com.studiofortress.sf.audio;

/**
 * This is the common interface for all Audio Players.
 *
 * Classes that implement this Audio Player should not play by default when they
 * are constructed. Play should require being called to start playing.
 * By default subclasses of AudioPlayer should also not repeat.
 *
 * An implementation of AudioPlayer must allow three unique states: playing,
 * stopped and paused. The isPlaying, isPaused and isStopped methods state what
 * defines the stopped, playing and paused states. When an AudioPlayer is
 * created it should begin in the stopped state by default. A player must always
 * be in one, and only one, of the three states.
 *
 * An AudioPlayer is also advised not to release resources, especially when it
 * is paused, as this can slowdown replaying music. It is advised to release
 * resources when it is finalised.
 *
 * @author Joseph Lenton
 * @version 30/12/2008
 */
public interface AudioPlayer
{
    /**
     * Begins playing this Audio Player and returns. The playing should occur
     * within another thread.
     */
    public abstract void play();

    /**
     * This does not take into account if the audio is actually working, just if
     * the AudioPlayer is set to be playing.
     * @return True if this is currently playing. False if not.
     */
    public abstract boolean isPlaying();

    /**
     * The Audio player stops playing. When followed by a call to play this will
     * begin playing from the beginning of the audio.
     */
    public abstract void stop();

    /**
     * This states that it is not playing and a call to play will start playing
     * from the beginning of the audio.
     * Stopped is the default state and after playing can only be reached by
     * a call to stop.
     * @return True if the AudioPlayer is in a stopped state.
     */
    public abstract boolean isStopped();

    /**
     * The Audio player stops playing. When followed by a call to play this will
     * begin playing from when the audio was paused.
     */
    public abstract void pause();

    /**
     * A paused state is where it has been playing and then paused. It is in a
     * state where it can continue to play from the moment when it was paused.
     * @return True if this audio is in a paused state.
     */
    public abstract boolean isPaused();

    /**
     * Sets this Audio player to repeat when it reaches the end of the sound.
     * @param repeat True if the audio should repeat at the end, false if not.
     */
    public abstract void setRepeat(boolean repeat);

    /**
     * @return True if this Audio Player will repeat when it reaches the end, false if not.
     */
    public abstract boolean isRepeating();

    /**
     * @param volume The new playback volume of this AudioPlayer, it must be a value from 0 to 100.
     */
    public abstract void setVolume(int volume);

    /**
     * @return The current level of the volume, a value from 0 to 100 (inclusive).
     */
    public abstract int getVolume();
}
